SCIM group management API
In SCIM , groups enable common group- or role-based access control models, as defined by the service provider such as STA. SCIM does not define the semantics of group membership, or any behavior or authorization granted as a result of membership. Rather, these are defined by STA.
The SCIM API for STA includes endpoints and operations for retrieving, creating, and updating groups.
Groups include the common attributes, core group attributes, and custom STA group attributes.
-
Core group schema: urn:ietf:params:scim:schemas:core:2.0:Group
-
STA Custom group schema: urn:ietf:params:scim:schemas:extension:stagroupextension:2.0:Group
See also the SCIM API limitations.
Retrieve Groups (GET)
GET /tenants/[tenantCode]/scim/v2/groups
Retrieve a list of SCIM groups for your virtual server (tenant). Nested groups are not returned.
The excludedAttributes property is supported only for use with GET groups, and the only valid attribute is members. Any other use of excludedAttributes is ignored.
To reduce the number of returned results, add an eq or and filter. For example:
GET /tenants/{tenantCode}/scim/v2/groups?filter=members.value eq "08D9B595B260F5AE01879255E21200000001"
The search filter can query the following attributes:
-
members.value
-
description
-
isSynchronized
Group members are not included in the response. To get membership details, use the Retrieve a specific group endpoint.
Sample response
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 3,
"itemsPerPage": 20,
"startIndex": 1,
"Resources": [
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group",
"urn:ietf:params:scim:schemas:extension:stagroupextension:2.0:Group"
],
"id": "16777217",
"externalId": "789012",
"displayName": "Marketing",
"urn:ietf:params:scim:schemas:extension:stagroupextension:2.0:Group": {
"description": "Marketing team members",
"isSynchronized": false
},
"meta": {
"resourceType": "Group",
"location": "http://localhost:5000/tenants/{tenantCode}/scim/v2/groups/16777217"
}
},
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group",
"urn:ietf:params:scim:schemas:extension:stagroupextension:2.0:Group"
],
"id": "16777218",
"externalId": "456789",
"displayName": "Accounting",
"urn:ietf:params:scim:schemas:extension:stagroupextension:2.0:Group": {
"description": "Accounting team members",
"isSynchronized": true
},
"meta": {
"resourceType": "Group",
"location": "http://localhost:5000/tenants/{tenantCode}/scim/v2/groups/16777218"
}
},
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group",
"urn:ietf:params:scim:schemas:extension:stagroupextension:2.0:Group"
],
"id": "16777219",
"externalId": "678543",
"displayName": "Sales",
"urn:ietf:params:scim:schemas:extension:stagroupextension:2.0:Group": {
"isSynchronized": false
},
"meta": {
"resourceType": "Group",
"location": "http://localhost:5000/tenants/{tenantCode}/scim/v2/groups/16777219"
}
}
]
}
Errors
| Error | Cause |
|---|---|
| 400 Bad request | Bad request |
| 401 Unauthorized | The apikey authorization header is missing or invalid. |
| 404 Not Found | The tenantCode is incorrect. |
| 500 Internal server error | The server was unable to process the request. |
Retrieve a specific group (GET)
GET /tenants/[tenantCode]/scim/v2/groups/[groupId]
Get the details for a specific group.
To exclude the list of members from the response, use excludedAttributes=members in the request. Only the members attribute can be excluded.
Sample response
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group",
"urn:ietf:params:scim:schemas:extension:stagroupextension:2.0:Group"
],
"id": "16777217",
"externalId": "876543",
"displayName": "Marketing",
"urn:ietf:params:scim:schemas:extension:stagroupextension:2.0:Group": {
"description": "Marketing team members",
"isSynchronized": false
},
"members": [
{
"value": "08D8DFE9CEDA6EE801A5584FEACD00000002",
"$ref": "http://localhost:5000/tenants/{tenantCode}/scim/v2/users/08D8DFE9CEDA6EE801A5584FEACD00000002",
"display": "Jim Albert"
},
{
"value": "88D8DF4E1EBC8E50A0FD82B1364900000002",
"$ref": "http://localhost:5000/tenants/{tenantCode}/scim/v2/users/88D8DF4E1EBC8E50A0FD82B1364900000002",
"display": "Michael Smith"
},
{
"value": "88D8EA34665AE7776BE8595301FD00000002",
"$ref": "http://localhost:5000/tenants/{tenantCode}/scim/v2/users/88D8EA34665AE7776BE8595301FD00000002",
"display": "Dwight Schneider"
}
],
"meta": {
"resourceType": "Group",
"location": "http://localhost:5000/tenants/{tenantCode}/scim/v2/groups/16777217"
}
}
Errors
| Error | Cause |
|---|---|
| 400 Bad Request | The user object ID is not hex-encoded. |
| 401 Unauthorized | The apikey authorization header is missing or invalid. |
| 404 Not Found | The tenantCode or user ID is incorrect. |
| 500 Internal server error | The server was unable to process the request. |
Create a group (POST)
POST /tenants/[tenantCode]/scim/v2/groups
Group members cannot be added when creating a group. To add group members, use the replace (PUT) or update (PATCH) a group request.
The name is required.
Errors
| Error | Cause |
|---|---|
| 400 Bad request | Bad request |
| 404 Not Found | The tenantCode is incorrect. |
| 409 Conflict | The requested userName or aliases are already in use. |
| 500 Internal server error | The server was unable to process the request. |
Update a group (PATCH)
PATCH /tenants/{tenantCode}/scim/v2/groups/{groupId}
Update one or more attributes for a specific group using a sequence of operations to add, remove, or replace values. The list of operations is passed to the API in the JSON body of the request.
The body of each request must contain the schemas attribute with the following URI value:
urn:ietf:params:scim:api:messages:2.0:PatchOp
The body of an HTTP patch request must contain the attribute Operations, whose value is an array of one or more patch operations. Each patch operation object must have exactly one op member, whose value indicates the operation to perform and can be one of add, remove, or replace.
To reset the value of a property, use an empty string ( “” ). However, you cannot reset the display field to empty.
Sample request
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations":[
{
"op":"add",
"path":"members",
"value":[
{
"value": "08D915FDEEDB03B50132D5E308E700000001"
},
{
"value": "08D919E85F47FD77019E8BED2E7B00000001"
}
]
}
]
}
Sample response
A maximum of 1000 members is returned in the response.
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group",
"urn:ietf:params:scim:schemas:extension:stagroupextension:2.0:Group"
],
"id": "16777217",
"externalId": "098523",
"displayName": "Group 1",
"urn:ietf:params:scim:schemas:extension:stagroupextension:2.0:Group": {
"description": "All about group 1.",
"isSynchronized": false
},
"members": [
{
"value": "08D915F5593ED5A40190DA1469D100000001",
"$ref": "http://localhost:5000/tenants/BY6XA80E9M/scim/v2/users/08D915F5593ED5A40190DA1469D100000001",
"display": "sas1"
},
{
"value": "08D915FDEEDB03B50132D5E308E700000001",
"$ref": "http://localhost:5000/tenants/BY6XA80E9M/scim/v2/users/08D915FDEEDB03B50132D5E308E700000001",
"display": "wla"
},
{
"value": "08D919E85F47FD77019E8BED2E7B00000001",
"$ref": "http://localhost:5000/tenants/BY6XA80E9M/scim/v2/users/08D919E85F47FD77019E8BED2E7B00000001",
"display": "wla2"
},
{
"value": "08D91F624E0CD34D010D348D78D800000001",
"$ref": "http://localhost:5000/tenants/BY6XA80E9M/scim/v2/users/08D91F624E0CD34D010D348D78D800000001",
"display": "test"
}
],
"meta": {
"resourceType": "Group",
"location": "http://localhost:5000/tenants/BY6XA80E9M/scim/v2/Groups/16777217"
}
}
Replace a group (PUT)
PUT /tenants/[tenantCode]/scim/v2/groups/[id]
Update the details of a specific group by completely replacing the group details. If existing values are not provided, they are removed.
To avoid losing or unintentionally over-writing group data, retrieve (GET) the group before you update (PUT) the group with any changes.
A maximum of 1000 users can be added to a group in a request. For groups that exceed this limitation, use PATCH.
Errors
| Error | Cause |
|---|---|
| 400 Bad request | Unable to update a group with more than 1000 members. |
| 401 Unauthorized | The apikey authorization header is missing or invalid. |
| 404 Not Found | The tenantCode or group ID is incorrect. |
| 409 Conflict | The requested group name is already in use. |
| 503 Out of resources | The maximum number of users is exceeded. |
Delete a group
DELETE /tenants/{tenantCode}/scim/v2/groups/{id}
Remove a specific group.
Errors
| Error | Cause |
|---|---|
| 400 Bad request | Unable to update a group with more than 1000 members. |
| 401 Unauthorized | The apikey authorization header is missing or invalid. |
| 404 Not Found | The tenantCode or group ID is incorrect. |
| 503 Out of resources | The maximum number of users is exceeded. |